//
//  MapbarGUID.h
//  MapbarGUID
//
//  Created by liushuai on 15/5/15.
//  Copyright (c) 2015 Mapbar Inc. All rights reserved.
//

#import <Foundation/Foundation.h>

/**
 *
 *  获得系统vendor id时使用的key
 *
 *  返回值的格式：
 *  遵循RFC 4122 version 4标准的字符串，例如：128AB319-82C6-4BD0-9A3B-EA3C53811E29
 *  
 */
extern NSString * __nonnull const kMapbarGUIDVendorIdentifier;

/**
 *
 *  获得系统广告id时使用的key
 *
 *  返回值的格式：
 *  遵循RFC 4122 version 4标准的字符串，例如：978CDA2D-71BF-4C64-B0D6-60662DB56144
 *
 */
extern NSString * __nonnull const kMapbarGUIDAdvertisingIdentifier;

/**
 *
 *  获得传统open udid时使用的key
 *
 *  返回值的格式：
 *  由0-9和A-F字母组成的32位字符串或40位字符串
 *
 */
extern NSString * __nonnull const kMapbarGUIDOpenUDIDIdentifier;

/**
 *
 *  图吧GUID包
 *
 */
@interface MapbarGUID : NSObject

/**
 *
 *  此方法会返回默认的GUID，供统计包等项目使用。
 *
 *  GUID的格式规则遵循RFC 4122 version 4标准，例如：03B541B1-528B-49BB-841B-FC40466E4B74。
 *
 *  @returns 默认的GUID
 *
 */
+ (nonnull NSString *)value;

/**
 *
 *  此方法会返回其他非标准的标识字符串，参数取值参见MapbarGUID.h中定义的字符串常量。
 *
 *  @param identifierKey 用于指定标识类型的字符串常量
 *
 *  @returns 指定的标识字符串，具体格式请参见头文件中各字符串常量的说明。找不到对应的标识时返回nil。
 *
 */
+ (nullable NSString *)identifierForKey:(nonnull NSString *)identiferKey;

/**
 *
 *  此方法是用来将客户端获取到的广告id传给GUID包并记录到内存。
 *
 *  如果客户端内展示了广告横幅、全屏广告等，可主动获取广告id，并调用此方法传给GUID包。注意GUID包只会将广告id记录到内存，因此需每次启动都调用此方法。
 *
 *  此外还请注意，规范要求客户端在获取广告id之前先判断用户是否允许收集（advertisingTrackingEnabled），客户端应仅在用户允许的情况下将广告id传入GUID包，如果用户不允许使用广告id，则不应调用此方法。
 *
 *  @discussion 之所以没有在GUID包中独立采集广告id，是因为苹果不允许应用将广告id用于非广告统计的用途，客户端将广告id用于其他用途，可能会导致App Store审核被拒。
 *
 *  @param identifier 以NSUUID形式表示的系统广告id
 *
 */
+ (void)setAdvertisingIdentifier:(nonnull NSUUID *)identifier;

@end
